#%RAML 1.0 Library
# TODO: This is almost a direct conversion from the original json schema
# and does not fully and accurately describe the exact behavior we have
# today. We should attempt to align this with the actual validation code.
uses:
  appContainer: appContainer.raml
  artifact: artifact.raml
  constraints: constraint.raml
  env: environmentVariable.raml
  health: healthCheck.raml
  check: check.raml
  label: label.raml
  network: network.raml
  number: numberTypes.raml
  readiness: readinessCheck.raml
  secrets: secrets.raml
  strings: stringTypes.raml
  task: task.raml
  versionInfo: versionInfo.raml
  pragma: pragma.raml
  unreachableStrategy: unreachableStrategy.raml
  killSelection: killSelection.raml
  resources: resources.raml

types:
  AppResidency:
    type: object
    description: |
      When using local persistent volumes that pin tasks onto agents,
      these values define how Marathon handles terminal states of these tasks.
    properties:
      relaunchEscalationTimeoutSeconds:
        type: integer
        format: int64
        minimum: 0
        default: 3600
        description:
          This property is deprecated and it has no effect.
          When a task using persistent local volumes cannot be restarted on the
          agent it's been pinned to, Marathon will try to launch this task on
          another node after this timeout. Defaults to 3600 (one hour).",
      taskLostBehavior:
        description:
          This property is deprecated and it has no effect.
        type: strings.TaskLostBehavior
        default: WAIT_FOREVER
  UpgradeStrategy:
    type: object
    description: |
      During an upgrade all instances of an application get replaced by a new
      version.
      The upgradeStrategy controls how Marathon stops old versions and
      launches new versions.
    properties:
      maximumOverCapacity:
        type: number
        format: double
        minimum: 0.0
        maximum: 1.0
        description: |
          A number between 0 and 1 which is multiplied with the instance count.
          This is the maximum number of additional instances launched at any
          point of time during the upgrade process.
      minimumHealthCapacity:
        type: number
        format: double
        minimum: 0.0
        maximum: 1.0
        description: |
          A number between 0 and 1 that is multiplied with the instance count.
          This is the minimum number of healthy nodes that do not sacrifice
          overall application purpose. Marathon will make sure, during the
          upgrade process, that at any point of time this number of healthy
          instances are up.
  App:
    type: object
    (pragma.generateUpdateType):
    properties:
      id: strings.PathId
      acceptedResourceRoles?:
        (pragma.forceOptional):
        type: array
        items: string
        uniqueItems: true
        example: [public-facing]
        description: |
          A list of resource roles.
          Marathon considers only resource offers with roles in this list for
          launching tasks of this app. If you do not specify this,
          Marathon considers all resource offers with roles that have been
          configured by the `--default_accepted_resource_roles` command line flag.
          If no `--default_accepted_resource_roles` was given on startup,
          Marathon considers all resource offers. To register Marathon for a role,
          you need to specify the `--mesos_role` command line flag on startup.
          If you want to assign all resources of a agent to a role,
          you can use the `--default_role` argument when starting up the agent.
          If you need a more fine-grained configuration, you can use the
          `--resources` argument to specify resource shares per role.
          See [the Mesos attribute and resources documentation](http://mesos.apache.org/documentation/latest/attributes-resources/) for details
      args?:
        type: array
        (pragma.omitEmpty):
        items: string
        description: |
          An array of strings that represents an alternative mode of specifying the
          command to run. This was motivated by safe usage of containerizer features
          like a custom Docker ENTRYPOINT. This args field may be used in place of
          cmd even when using the default command executor.
          This change mirrors API and semantics changes in the Mesos CommandInfo
          protobuf message starting with version `0.20.0`.
          Either `cmd` or `args` must be supplied.
          It is invalid to supply both `cmd` and `args` in the same app.
      backoffFactor?:
        type: number
        format: double
        minimum: 1.0
        default: 1.15
        description: |
          Configures exponential backoff behavior when launching potentially sick
          apps. This prevents sandboxes associated with consecutively failing tasks
          from filling up the hard disk on Mesos agents.
          The backoff period is multiplied by the factor for each consecutive
          failure until it reaches maxLaunchDelaySeconds.
          This applies also to tasks that are killed due to failing too
          many health checks.
      backoffSeconds?:
        type: integer
        format: int32
        minimum: 0
        default: 1
        description: |
          Configures exponential backoff behavior when launching potentially sick
          apps. This prevents sandboxes associated with consecutively failing tasks
          from filling up the hard disk on Mesos agents.
          The backoff period is multiplied by the factor for each consecutive
          failure until it reaches maxLaunchDelaySeconds.
          This applies also to tasks that are killed due to failing too
          many health checks.
      cmd?:
        type: string
        minLength: 1
        description: |
          The command that is executed.  This value is wrapped by Mesos via
          `/bin/sh -c ${app.cmd}`.
          Either `cmd` or `args` must be supplied.
          It is invalid to supply both `cmd` and `args` in the same app.
      constraints?:
        type: array
        (pragma.omitEmpty):
        items: constraints.AppConstraint
        uniqueItems: true
      container?: appContainer.Container
      cpus?:
        type: number
        format: double
        default: 1
        description: |
          The number of CPU shares this application needs per instance. This number does not have to be integer, but can be a fraction.",
        minimum: 0.001
      dependencies?:
        type: array
        (pragma.omitEmpty):
        items: strings.PathId
        uniqueItems: true
        description: |
          A list of services upon which this application depends
          An order is derived from the dependencies for performing start/stop and
          upgrade of the application. For example, an application /a relies on the
          services /b which itself relies on /c. To start all 3 applications, first
          /c is started than /b than /a.
      disk?:
        type: number
        default: 0
        description: |
          How much disk space is needed for this application.
          This number does not have to be an integer, but can be a fraction.
        format: double
        minimum: 0
      env?:
        type: env.LegacyEnvVars
        (pragma.omitEmpty):
      executor?:
        type: string
        pattern: ^(//cmd)|(/?[^/]+(/[^/]+)*)|$
        default: ""
        description: |
          The executor to use to launch this application.
          Different executors are available.
          The simplest one (and the one configured by default if none is given) is `//cmd`,
          which takes the cmd and executes that on the shell level.
      executorResources?:
        type: resources.ExecutorResources
        description: The resources to allocate to the executor.
      fetch?:
        type: artifact.Artifact[]
        (pragma.omitEmpty):
        description: Provided URIs are passed to Mesos fetcher module and resolved in runtime.
      healthChecks?:
        type: health.AppHealthCheck[]
        (pragma.omitEmpty):
        uniqueItems: true
      check?:
        type: check.AppCheck
      instances?:
        type: integer
        format: int32
        minimum: 0
        default: 1
        description: |
          The number of instances of this application to start.
          Please note: this number can be changed any time as needed to
          scale the application.
      labels?: label.KVLabels
      maxLaunchDelaySeconds?:
        type: integer
        format: int32
        minimum: 0
        default: 300
        description: |
          Configures exponential backoff behavior when launching potentially sick
          apps. This prevents sandboxes associated with consecutively failing tasks
          from filling up the hard disk on Mesos agents.
          The backoff period is multiplied by the factor for each consecutive
          failure until it reaches maxLaunchDelaySeconds.
          This applies also to tasks that are killed due to failing too many health checks.
      mem?:
        type: number
        format: double
        minimum: 0
        default: 128
        description: |
          The amount of memory in MB that is needed for the application per instance.
      gpus?:
        type: integer
        format: int32
        minimum: 0
        default: 0
        description: |
          The amount of GPU cores that is needed for the application per instance.
      ipAddress?:
        type: network.IpAddress
        (pragma.deprecated): Use `networks` instead.
      networks?:
        type: array
        items: network.Network
      ports?:
        type: array
        (pragma.forceOptional):
        (pragma.deprecated): Use `portDefinitions` instead.
        items: number.AnyPort
        description: |
          An array of required port resources on the agent host.
          The number of items in the array determines how many dynamic ports are
          allocated for every task.
          For every port that is zero, a globally unique (cluster-wide) port is
          assigned and provided as part of the app definition to be used in load
          balancing definitions.
        usage: |
          made this and `portDefinitions` force-optional because otherwise it's impossible
          to tell the difference between the user specifying an empty array or no array
          at all.
      portDefinitions?:
        type: network.PortDefinition[]
        (pragma.forceOptional):
        description: |
          An array of required port resources on the agent host.
          The number of items in the array determines how many dynamic ports are
          allocated for every task. For every port definition with port number zero,
          a globally unique (cluster-wide) service port is assigned and provided as
          part of the app definition to be used in load balancing definitions.
        usage: |
          made this and `ports` force-optional because otherwise it's impossible to tell
          the difference between the user specifying an empty array or no array at all.
      readinessChecks?:
        type: readiness.ReadinessCheck[]
        (pragma.omitEmpty):
      residency?:
        type: AppResidency
        description:
          This property is deprecated and it has no effect.
      resourceLimits?:
        type: resources.ResourceLimits
        description: |
          Specify optional resource limits for a container, allowing the task to consume more cpu and memory resources
          than requested, if available.
      requirePorts?:
        type: boolean
        description: |
          Applies only for host networking.
          Normally, the host ports of your tasks are automatically assigned.
          This corresponds to the requirePorts value false which is the default.
          If you need more control and want to specify your host ports in advance,
          you can set requirePorts to true. This way the ports you have specified
          are used as host ports. That also means that Marathon can schedule the
          associated tasks only on hosts that have the specified ports available.
        default: false
      secrets?:
        type: secrets.Secrets
        (pragma.omitEmpty):
      taskKillGracePeriodSeconds?:
        type: integer
        format: int32
        minimum: 0
        description: |
          Configures the number of seconds between escalating from SIGTERM to
          SIGKILL when signalling tasks to terminate.
          Using this grace period, tasks should perform orderly shut down
          immediately upon receiving SIGTERM.
      upgradeStrategy?: UpgradeStrategy
      uris?:
        type: array
        (pragma.forceOptional):
        (pragma.deprecated): Use `fetch` instead.
        items:
          type: strings.Uri
        description: |
          URIs defined here are resolved, before the application gets started.
          If the application has external dependencies, they should be defined here.
        usage: force-optional so that we can differentiate at validation/conversion time.
      user?:
        type: string
        description: The user to use to run the tasks on the agent.
      version?:
        type: datetime
        description: The version of this definition
      versionInfo?: versionInfo.VersionInfo
      killSelection?:
        type: killSelection.KillSelection
        default: YOUNGEST_FIRST
      unreachableStrategy?: unreachableStrategy.UnreachableStrategy
      tty?:
        type: boolean
        description: |
          Describes if (pseudo) TTY sould be allocated for the process of this container.
      role?:
        type: string
        minLength: 1
        description: |
          The role to use. If not specified, uses the role of the enclosing group, or the default role.
          At the moment, only the default role or the group role are allowed
  AppList:
    type: object
    (pragma.serializeOnly): # Used only for serialization
    properties:
      apps: AppInfo[]

  VersionList:
    type: object
    properties:
      versions: datetime[]

  AppInfo:
    type: App
    (pragma.serializeOnly): # Used only for serialization
    properties:
      tasksStaged?:
        type: integer
        format: int32
      tasksRunning?:
        type: integer
        format: int32
      tasksHealthy?:
        type: integer
        format: int32
      tasksUnhealthy?:
        type: integer
        format: int32
      deployments?:
        type: strings.Identifiable[]
        (pragma.forceOptional):
      readinessCheckResults?:
        type: readiness.TaskReadinessCheckResult[]
        (pragma.forceOptional):
      tasks?:
        type: task.Task[]
        (pragma.forceOptional):
      lastTaskFailure?: task.TaskFailure
      tasksStats?: task.TaskStatsByVersion

